IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/g_man/cat3/ftn/lrectr.z/lrectr

Text File | 2002-10-03 | 6.7 KB | 199 lines

llllrrrreeeeccccttttrrrr((((3333GGGG))))                                                          llllrrrreeeeccccttttrrrr((((3333GGGG))))



NNNNAAAAMMMMEEEE
     rrrreeeeccccttttrrrreeee,,,, llllrrrreeeeccccttttrrrr - reads a rectangular array of pixels into CPU memory

FFFFOOOORRRRTTTTRRRRAAAANNNN 77777777 SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
     iiiinnnntttteeeeggggeeeerrrr****4444 rrrreeeeccccttttrrrreeee((((xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222,,,, ppppaaaarrrrrrrraaaayyyy))))
     iiiinnnntttteeeeggggeeeerrrr****4444 xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222
     iiiinnnntttteeeeggggeeeerrrr****2222 ppppaaaarrrrrrrraaaayyyy((((****))))

     iiiinnnntttteeeeggggeeeerrrr****4444 llllrrrreeeeccccttttrrrr((((xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222,,,, ppppaaaarrrrrrrraaaayyyy))))
     iiiinnnntttteeeeggggeeeerrrr****4444 xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222
     iiiinnnntttteeeeggggeeeerrrr****4444 ppppaaaarrrrrrrraaaayyyy((((****))))

PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
     _x_1       expects the x coordinate of the lower-left corner of the
              rectangle that you want to read.

     _y_1       expects the y coordinate of the lower-left corner of the
              rectangle that you want to read.

     _x_2       expects the x coordinate of the upper-right corner of the
              rectangle that you want to read.

     _y_2       expects the y coordinate of the upper-right corner of the
              rectangle that you want to read.

     _p_a_r_r_a_y   expects the array to receive the pixels that you want to read.

FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
     The returned value of this function is the number of pixels specified in
     the rectangular region, regardless of whether the pixels were actually
     readable (i.e. on-screen) or not.
























                                                                        PPPPaaaaggggeeee 1111






llllrrrreeeeccccttttrrrr((((3333GGGG))))                                                          llllrrrreeeeccccttttrrrr((((3333GGGG))))



DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     rrrreeeeccccttttrrrreeee and llllrrrreeeeccccttttrrrr read the pixel values of a rectangular region of the
     screen and write them to the array, _p_a_r_r_a_y. The system fills the elements
     of _p_a_r_r_a_y from left-to-right, then bottom-to-top.  All coordinates are
     relative to the lower-left corner of the window, not the screen or
     viewport.

     Pixels are read from the currently active framebuffer, as specified by
     ddddrrrraaaawwwwmmmmoooo....  Thus, to read pixel values from the overlay bitplanes, for
     example, simply set ddddrrrraaaawwwwmmmmoooo to OOOOVVVVEEEERRRRDDDDRRRR.  Use rrrreeeeaaaaddddssssoooo to specify the pixel
     source within the current framebuffer (backbuffer, frontbuffer, or z-
     buffer, for example) from which both rrrreeeeccccttttrrrreeee and llllrrrreeeeccccttttrrrr take pixel values.

     rrrreeeeccccttttrrrreeee fills an array of 16-bit words, and therefore should be used only
     to read color index values.  llllrrrreeeeccccttttrrrr fills an array of 32-bit words.
     Based on the current ppppiiiixxxxmmmmoooodddd, llllrrrreeeeccccttttrrrr can return pixels of 1, 2, 4, 8, 12,
     16, 24, or 32 bits each.  Use llllrrrreeeeccccttttrrrr to read packed RGB or RGBA values,
     color index values, or _z values.

     ppppiiiixxxxmmmmoooodddd greatly affects the operation of llllrrrreeeeccccttttrrrr, and has no effect on the
     operation of rrrreeeeccccttttrrrreeee.  By default, llllrrrreeeeccccttttrrrr returns 32-bit pixels in the
     format used by ccccppppaaaacccckkkk.  Different pixel sizes, framebuffer shifts, scan
     patterns through the framebuffer, and offsets through memory, can all be
     specified using ppppiiiixxxxmmmmoooodddd

     rrrreeeeccccttttrrrreeee and llllrrrreeeeccccttttrrrr leave the current character position unpredictable.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     cpack, drawmo, lrectw, pixmod, readso

NNNNOOOOTTTTEEEESSSS
     These routines are available only in immediate mode.

     On IRIS-4D GT and GTX models, returned bits that do not correspond to
     valid bitplanes are undefined.  Other models return zero in these bits.

     On IRIS-4D GT, GTX, XS, XS24, XZ, Elan, Extreme and VGX models, rrrreeeeccccttttrrrreeee
     performance will suffer if _x_2 - _x_1 + 1 is odd, or if _p_a_r_r_a_y is not 32-bit
     word aligned.

     Due to the write-back nature of the R4000 cache, sproc/m_fork processes
     should avoid accesses to cache lines (128 Bytes) to which a pixel read is
     currently in progress.

     The size of the array passed to llllrrrreeeeccccttttrrrr is limited to the size of the
     screen.

BBBBUUUUGGGGSSSS
     On IRIS-4D GT and GTX models, when reading pixels from the PUPMODE
     planes, the returned bits are shifted up by two bits.





                                                                        PPPPaaaaggggeeee 2222






llllrrrreeeeccccttttrrrr((((3333GGGG))))                                                          llllrrrreeeeccccttttrrrr((((3333GGGG))))



     IRIS-4D VGX and VGXT require that both |x2-x1+1| and |y2-y1+1| be less
     than 2048.





















































                                                                        PPPPaaaaggggeeee 3333